Summary

Adds multi-environment publish to a single shared Azure APIM instance via a new optional environment: block in configuration.<env>.yaml override files. Resource names are namespaced by namePrefix and/or nameSuffix, and API paths can be scoped by apiPathPrefix.

Related Issue(s)

Closes #132

What's included

New capability

• environment: block in override files — configures per-environment name and path affixing so dev, qa, and prod can share one APIM
• --delete-unmatched is now namespace-scoped when environment: is configured — a dev publish cannot delete prod resources on the shared instance
• Automatic policy XML rewriting — {{namedValue}} tokens, fragment-id, and backend-id attributes are rewritten to affixed names at publish time
• Cross-resource reference rewriting — subscription scopes, apiRelease apiIds, MCP tool operation ids, and PolicyFragment references

Safety guardrails

• Hard-block when environment: is present but both namePrefix and nameSuffix are missing/empty — path-only mode is intentionally unsupported because --delete-unmatched would silently destroy other environments' resources
• Character validation on affixes ([A-Za-z0-9-] only)
• Whitespace-only affixes rejected (trimmed to empty → error)
• appliesTo validation catches unknown or non-affixable resource types

New files

• src/services/env-mapper.ts — pure name/descriptor mapping module
• src/services/env-mapping-validator.ts — pre-flight validator with hard-block for unsafe configurations
• src/services/policy-ref-rewriter.ts — regex-based policy XML ref rewriter
• docs/guides/multi-environment-shared-apim.md — new 440-line user guide with setup, safety notes, examples, and troubleshooting

Modified files

• src/services/publish-service.ts — orchestration wiring; incremental-mode uses full listResources for validator and known-artifact set
• src/services/resource-publisher.ts — mapDescriptor applied at 5 PUT boundaries; 4 normalizers extended; NamedValue displayName / Api path prefix / PolicyFragment content / policy XML rewriting
• src/services/delete-unmatched-service.ts — namespace scoping via toCanonicalDescriptor
• src/models/config.ts — EnvironmentOverride, KnownArtifactSets, extended PublishConfig
• src/lib/config-loader.ts, src/services/override-merger.ts — schema-loader wiring
• schemas/v1/override-config.schema.json — additive schema extension (v1 stays v1)
• src/templates/configs/override-config.yaml, src/templates/copilot/configure-overrides-prompt.md — init scaffold
• README.md, docs/guides/environment-overrides.md — cross-links to new guide

Tests

• 6 new test files (env-mapper, policy-ref-rewriter, config.environment schema, delete-unmatched env-mapping, publish-service env-mapping, resource-publisher env-mapping)
• 4 existing test files extended
• 130+ new tests total; all 1234 tests pass

Design decisions (locked in with @petehauge)

1. Both name and displayName are affixed for NamedValues so {{token}} references in policies work across environments
2. Regex-based policy XML rewriting for {{token}} + targeted fragment-id/backend-id attributes (no full XML parse)
3. Explicit per-API path override wins over apiPathPrefix
4. Documentation, GlobalSchema, and PolicyRestriction are opt-in only (not in DEFAULT_APPLIES_TO)
5. Schema stays v1 (additive change, no version bump)
6. Path-only mode is blocked at validation time (see safety guardrails)

Reviews

Four internal squad reviews performed on this branch:

• CodeReviewer: APPROVE (one non-blocking wording nit)
• SecurityExpert: CLEAR (no findings)
• ApiOpsLead: APPROVE-WITH-CONCERNS (required fix applied: import.meta.url in test)
• ApimExpert: APPROVE-WITH-CONCERNS

Testing

npm test          # 1234/1234 pass (excluding known pre-existing Windows CLI-help flake)
npm run lint      # clean
npx tsc --noEmit  # clean